cpy

What is cpy?

The cpy npm package is a simple file copying utility for Node.js. It allows you to copy files or directories from one location to another with various options such as overwriting existing files, preserving directory structure, and more.

What are cpy's main functionalities?

Copy files

This feature allows you to copy files matching a specific pattern (e.g., all PNG files in the 'source' directory) to a destination directory.

const cpy = require('cpy');

cpy(['source/*.png'], 'destination').then(() => {
  console.log('Files copied!');
});

Copy files with options

This feature allows you to copy files with additional options such as not overwriting existing files (`overwrite: false`) and preserving the directory structure (`parents: true`).

const cpy = require('cpy');

cpy(['source/*.png'], 'destination', {
  overwrite: false,
  parents: true
}).then(() => {
  console.log('Files copied with options!');
});

Copy and rename

This feature allows you to copy a file and rename it in the destination directory using a rename function.

const cpy = require('cpy');

cpy(['source/file.txt'], 'destination', {
  rename: basename => `new-${basename}`
}).then(() => {
  console.log('File copied and renamed!');
});

Other packages similar to cpy

ncp

The ncp (node-copy-paste) package is similar to cpy and provides asynchronous recursive file copying with Node.js. It is an older package and does not provide as modern a syntax as cpy, which uses promises.

fs-extra

fs-extra is a package that extends the built-in fs module and includes file copying functionality. It offers a broader set of file system operations compared to cpy, including copying, moving, deleting files, and more.

copyfiles

copyfiles is a package that provides a command-line utility to copy files. It can be used in npm scripts and has a flat option to copy all files to a single directory level. It is less feature-rich than cpy when it comes to API usage within Node.js code.

README

cpy

Copy files

Why

• Fast by using streams.
• Resilient by using graceful-fs.
• User-friendly by accepting globs and creating non-existent destination directories.
• User-friendly error messages.
• Progress reporting.

Install

$ npm install cpy

Usage

const cpy = require('cpy');

(async () => {
	await cpy(['source/*.png', '!source/goat.png'], 'destination');
	console.log('Files copied!');
})();

API

cpy(source, destination, options?)

Returns a Promise<string[]> with the destination file paths.

source

Type: string | string[]

Files to copy.

If any of the files do not exist, an error will be thrown (does not apply to globs).

destination

Type: string

Destination directory.

options

Type: object

Options are passed to globby.

In addition, you can specify the below options.

cwd

Type: string
Default: process.cwd()

Working directory to find source files.

overwrite

Type: boolean
Default: true

Overwrite existing files.

parents

Type: boolean
Default: false

Preserve path structure.

rename

Type: string | Function

Filename or function returning a filename used to rename every file in source.

const cpy = require('cpy');

(async () => {
	await cpy('foo.js', 'destination', {
		rename: basename => `prefix-${basename}`
	});
})();

concurrency

Type: number
Default: (os.cpus().length || 1) * 2

Number of files being copied concurrently.

ignoreJunk

Type: boolean
Default: true

Ignores junk files.

filter

Type: Function

Function to filter files to copy.

Receives a source file object as the first argument.

Return true to include, false to exclude. You can also return a Promise that resolves to true or false.

const cpy = require('cpy');

(async () => {
	await cpy('foo', 'destination', {
		filter: file => file.extension !== 'nocopy'
	});
})();

Source file object

path

Type: string
Example: '/tmp/dir/foo.js'

Resolved path to the file.

relativePath

Type: string
Example: 'dir/foo.js' if cwd was '/tmp'

Relative path to the file from cwd.

name

Type: string
Example: 'foo.js'

Filename with extension.

nameWithoutExtension

Type: string
Example: 'foo'

Filename without extension.

extension

Type: string
Example: 'js'

File extension.

Progress reporting

cpy.on('progress', handler)

handler(progress)

Type: Function

progress

{
	completedFiles: number,
	totalFiles: number,
	completedSize: number,
	percent: number
}

• completedSize is in bytes
• percent is a value between 0 and 1

Note that the .on() method is available only right after the initial cpy call, so make sure you add a handler before awaiting the promise:

(async () => {
	await cpy(source, destination).on('progress', progress => {
		// …
	});
})();

Related

• cpy-cli - CLI for this module
• cp-file - Copy a single file
• move-file - Move a file
• make-dir - Make a directory and its parents if needed